File Management APIs

Comprehensive file management functionality for selecting files and opening them with external applications in universal apps.

File Management APIs

Comprehensive file management functionality for selecting files and opening them with external applications in universal apps.

🔄 Common Interface

All hooks now follow a standardized interface with execute() as the primary function,data for results, loading for state tracking, and built-in error handling.

useFilePicker() Hook

File selection with configurable picker options (multiple files, count and size limits), standardized progress tracking, and comprehensive error handling.

Property	Input	Output	Description
data	`-`	`object \| null`	Normalized picker payload containing files[], count, totalSize, transport, and legacy fileSrc/fileName for compatibility.
selectedFiles	`-`	`array`	Array of normalized file entries returned by the picker (one entry per selected file).
loading	`-`	`boolean`	Loading state during file selection operation.
error	`-`	`object \| null`	Standardized error object with code, category, message, details, and recovery info.
progress	`-`	`object \| null`	Progress tracking with opening/processing/routing phases and transport metadata.
isWeb	`-`	`boolean`	Environment detection flag for web context.
isNative	`-`	`boolean`	Environment detection flag for native app context.
execute	`options?: string \| FilePickerOptions`	`void`	Primary function to open the file picker. Accepts a MIME type string or a `FilePickerOptions` object with `mimeType`, `multiple`, `minFiles`, `maxFiles`, `minFileSize`, and `maxFileSize`.
pickFile	`options?: string \| FilePickerOptions`	`void`	Semantic alias for execute() when you prefer imperative naming.
getFileObject	`index?: number`	`Promise<File>`	Lazily converts the selected entry at index (default 0) into a browser File instance.
getAllFileObjects	`-`	`Promise<File[]>`	Resolves every selected entry into a File array for uploads or FormData.
canCreateFileObject	`-`	`boolean`	Indicates whether the first selected file transport supports File conversion.
canCreateFileObjects	`-`	`boolean[]`	Per-file transport capability flags matching the order of selectedFiles.
clear	`-`	`void`	Clear selected file data and reset all states.
clearError	`-`	`void`	Clear error state only, keeping file data intact.

useIntent() Hook

Open files with external applications using standardized interface with Android intents and iOS document interaction support.

Property	Input	Output	Description
data	`-`	`object \| null`	Result data from intent operation including success status
loading	`-`	`boolean`	Loading state during intent processing
error	`-`	`object \| null`	Standardized error object with recovery information
progress	`-`	`object \| null`	Progress tracking during intent operation
isWeb	`-`	`boolean`	Environment detection flag for web context
isNative	`-`	`boolean`	Environment detection flag for native app context
execute	`fileUrl: string, mimeType?: string`	`void`	Primary function to open file with external app. Requires file URL, optional MIME type for better app matching. See MIME Types Reference for complete list.
clear	`-`	`void`	Clear intent data and reset all states
clearError	`-`	`void`	Clear error state only

📁 File Management Example

Select single or multiple files with picker constraints, inspect metadata, and open them with external applications.

FileManagementDemo.js

1import React from 'react';
2import { useFilePicker } from "catalyst-core/hooks";
3
4function FileManagementApp() {
5  const { 
6    data: fileData, 
7    selectedFiles, 
8    execute: executeFilePicker
9  } = useFilePicker();
10
11  return (
12    <div style={{ padding: '20px', maxWidth: '600px' }}>
13      <h2>📁 File Management Demo</h2>
14      
15      {/* File Picker Section */}
16      <div style={{ marginBottom: '30px', padding: '15px', backgroundColor: '#f9f9f9', borderRadius: '8px' }}>
17        <h3>📂 File Picker</h3>
18        
19        <div style={{ marginBottom: '15px' }}>
20          <button 
21            onClick={() => executeFilePicker({ mimeType: 'image/*' })} 
22            
23            style={{ padding: '10px 15px', marginRight: '10px', fontSize: '14px' }}
24          >
25            '📁 Pick Image'
26          </button>
27          
28          <button 
29            onClick={() => executeFilePicker({ mimeType: 'application/pdf' })} 
30            
31            style={{ padding: '10px 15px', marginRight: '10px', fontSize: '14px' }}
32          >
33            '📄 Pick PDF'
34          </button>
35          
36          <button 
37            onClick={() => executeFilePicker({
38              mimeType: '*/*',
39              multiple: true,
40              maxFiles: 3,
41              maxFileSize: 10 * 1024 * 1024,
42            })} 
43            
44            style={{ padding: '10px 15px', fontSize: '14px' }}
45          >
46            '🗂️ Pick up to 3 files'
47          </button>
48          
49          
50        </div>
51
52        {fileData && (
53          <div style={{ 
54            padding: '10px', 
55            backgroundColor: '#e8f5e8', 
56            borderRadius: '4px',
57            marginBottom: '10px'
58          }}>
59            <p><strong>Selection Summary</strong></p>
60            <p>📦 Files Selected: {fileData.count}</p>
61            {typeof fileData.totalSize === 'number' && (
62              <p>📏 Total Size: {(fileData.totalSize / 1024).toFixed(2)} KB</p>
63            )}
64            <p>🔗 Primary MIME: {fileData.mimeType || 'Unknown'}</p>
65            <p>🚚 Transport: {fileData.transport}</p>
66            
67            
68            {fileData.options && (
69              <details style={{ marginTop: '10px' }}>
70                <summary>Picker options</summary>
71                <pre style={{ marginTop: '6px', background: '#fff', padding: '8px', borderRadius: '4px' }}>
72                  {JSON.stringify(fileData.options, null, 2)}
73                </pre>
74              </details>
75            )}
76            
77            <div style={{ marginTop: '12px' }}>
78              <p><strong>Files</strong></p>
79              {selectedFiles.map((file, index) => (
80                <div 
81                  key={index}
82                  style={{ 
83                    marginBottom: '8px',
84                    backgroundColor: '#fff',
85                    padding: '8px',
86                    borderRadius: '4px',
87                    border: '1px solid #cce5cc'
88                  }}
89                >
90                  <p>📄 Name: {file.fileName || file.name}</p>
91                  <p>📏 Size: {typeof file.size === 'number' ? (file.size / 1024).toFixed(2) : '0'} KB</p>
92                  <p>🔗 Type: {file.mimeType || file.type || 'Unknown'}</p>
93                  <p>🚚 Transport: {file.transport || 'N/A'}</p>
94                  
95                </div>
96              ))}
97            </div>
98            
99            
100          </div>
101        )}
102      </div>
103    </div>
104  );
105}
106
107export default FileManagementApp;

Platform & Device Behavior

File management API behavior varies across different platforms and device types. See detailed breakdown below.

Platform	Status	Behavior	Notes
🤖 Android Emulator	`✅ Supported`	File picker works with emulator file system. File intents open with available apps.	Uses Android Virtual Device file system and app intents
🤖 Android Physical	`✅ Supported`	Full file picker functionality with device storage. File intents use installed apps.	Requires storage permissions. Works with all installed apps.
🍎 iOS Simulator	`✅ Supported`	iOS file picker and intent functionality currently in development.	File management features not yet implemented for iOS Simulator
🍎 iOS Physical	`⏳ Coming Soon`	iOS file picker and intent functionality currently in development.	Native iOS Files app integration planned for future release
🌐 Web Browser	`🔄 Fallback`	Browser file picker for uploads. Limited file opening capabilities.	Browser security restrictions apply. Limited MIME type support.

Important Notes

Platform Support: Works on both iOS and Android native apps
MIME Types: Use specific MIME types for better file filtering (e.g., "image/*", "application/pdf")
File Access: Selected files provide URI for further processing or opening with intents
Error Handling: Both hooks include comprehensive error handling for failed operations
State Management: Processing states help provide user feedback during operations
Web Fallback: Returns safe defaults when running in web mode

File Management APIs